---
title: 调试
description: 模型上下文协议（MCP）集成的全面调试指南
---

在开发 MCP 服务器或将其集成到应用程序时，有效的调试至关重要。本指南涵盖了 MCP 生态系统中可用的调试工具和方法。

<Info>
  本指南适用于 macOS。其他平台的指南即将推出。
</Info>

## 调试工具概览

MCP 提供了多种工具，用于在不同层面进行调试：

1. **MCP 检查器**
   - 交互式调试界面
   - 直接服务器测试
   - 详情请见 [检查器指南](/docs/tools/inspector)

2. **Claude 桌面版开发者工具**
   - 集成测试
   - 日志收集
   - Chrome 开发者工具集成

3. **服务器日志**
   - 自定义日志实现
   - 错误跟踪
   - 性能监控

## 在 Claude 桌面版中调试

### 检查服务器状态

Claude.app 界面提供了基本的服务器状态信息：

1. 点击 <img src="/images/claude-desktop-mcp-plug-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> 图标查看：
   - 已连接的服务器
   - 可用提示和资源

2. 点击 <img src="/images/claude-desktop-mcp-hammer-icon.svg" style={{display: 'inline', margin: 0, height: '1.3em'}} /> 图标查看：
   - 模型可用的工具

### 查看日志

从 Claude 桌面版查看详细的 MCP 日志：

```bash
# 实时跟踪日志
tail -n 20 -F ~/Library/Logs/Claude/mcp*.log
```

日志捕获以下内容：
- 服务器连接事件
- 配置问题
- 运行时错误
- 消息交换

### 使用 Chrome 开发者工具

在 Claude 桌面版内部访问 Chrome 的开发者工具以调查客户端错误：

1. 创建一个 `developer_settings.json` 文件，将 `allowDevTools` 设置为 true：

```bash
echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json
```

2. 打开开发者工具：`Command-Option-Shift-i`

注意：您将看到两个开发者工具窗口：
- 主内容窗口
- 应用程序标题栏窗口

使用控制台面板检查客户端错误。

使用网络面板检查：
- 消息负载
- 连接时间

## 常见问题

### 工作目录

在使用 Claude 桌面版与 MCP 服务器时：

- 通过 `claude_desktop_config.json` 启动的服务器的工作目录可能是未定义的（例如 macOS 上的 `/`），因为 Claude 桌面版可能从任何位置启动
- 在配置和 `.env` 文件中始终使用绝对路径以确保可靠运行
- 通过命令行直接测试服务器时，工作目录将是您运行命令的目录

例如，在 `claude_desktop_config.json` 中使用：
```json
{
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/data"]
}
```
而不是相对路径，如 `./data`

### 环境变量

MCP 服务器仅自动继承部分环境变量，例如 `USER`、`HOME` 和 `PATH`。

要覆盖默认变量或提供您自己的变量，可以在 `claude_desktop_config.json` 中指定 `env` 键：

```json
{
  "myserver": {
    "command": "mcp-server-myapp",
    "env": {
      "MYAPP_API_KEY": "some_key",
    }
  }
}
```

### 服务器初始化

常见的初始化问题：

1. **路径问题**
   - 服务器可执行文件路径错误
   - 缺少所需文件
   - 权限问题
   - 尝试为 `command` 使用绝对路径

2. **配置错误**
   - 无效的 JSON 语法
   - 缺少必需字段
   - 类型不匹配

3. **环境问题**
   - 缺少环境变量
   - 环境变量值错误
   - 权限限制

### 连接问题

当服务器无法连接时：

1. 检查 Claude 桌面版日志
2. 验证服务器进程是否正在运行
3. 使用 [检查器](/docs/tools/inspector) 进行独立测试
4. 验证协议兼容性

## 实现日志记录

### 服务器端日志

在构建使用本地标准输入输出 [传输](/docs/concepts/transports) 的服务器时，所有记录到标准错误（stderr）的消息都将被主机应用程序（例如 Claude 桌面版）自动捕获。

<Warning>
  本地 MCP 服务器不应将消息记录到标准输出（stdout），因为这会干扰协议操作。
</Warning>

对于所有 [传输](/docs/concepts/transports)，您还可以通过发送日志消息通知向客户端提供日志：

<Tabs>
  <Tab title="Python">
    ```python
    server.request_context.session.send_log_message(
      level="info",
      data="服务器启动成功",
    )
    ```
  </Tab>
  <Tab title="TypeScript">
    ```typescript
    server.sendLoggingMessage({
      level: "info",
      data: "服务器启动成功",
    });
    ```
  </Tab>
</Tabs>

应记录的重要事件：
- 初始化步骤
- 资源访问
- 工具执行
- 错误情况
- 性能指标

### 客户端日志

在客户端应用程序中：

1. 启用调试日志
2. 监控网络流量
3. 跟踪消息交换
4. 记录错误状态

## 调试工作流程

### 开发周期

1. 初步开发
   - 使用 [检查器](/docs/tools/inspector) 进行基本测试
   - 实现核心功能
   - 添加日志点

2. 集成测试
   - 在 Claude 桌面版中测试
   - 监控日志
   - 检查错误处理

### 测试更改

为了高效测试更改：

- **配置更改**：重启 Claude 桌面版
- **服务器代码更改**：使用 Command-R 重新加载
- **快速迭代**：在开发期间使用 [检查器](/docs/tools/inspector)

## 最佳实践

### 日志策略

1. **结构化日志**
   - 使用一致的格式
   - 包含上下文
   - 添加时间戳
   - 跟踪请求 ID

2. **错误处理**
   - 记录堆栈跟踪
   - 包含错误上下文
   - 跟踪错误模式
   - 监控恢复情况

3. **性能跟踪**
   - 记录操作时间
   - 监控资源使用情况
   - 跟踪消息大小
   - 测量延迟

### 安全考虑

在调试时：

1. **敏感数据**
   - 清理日志
   - 保护凭据
   - 屏蔽个人信息

2. **访问控制**
   - 验证权限
   - 检查认证
   - 监控访问模式

## 获取帮助

遇到问题时：

1. **初步步骤**
   - 检查服务器日志
   - 使用 [检查器](/docs/tools/inspector) 测试
   - 审查配置
   - 验证环境

2. **支持渠道**
   - GitHub 问题
   - GitHub 讨论

3. **提供信息**
   - 日志摘录
   - 配置文件
   - 重现步骤
   - 环境详情

## 下一步

<CardGroup cols={2}>
  <Card
    title="MCP 检查器"
    icon="magnifying-glass"
    href="/docs/tools/inspector"
  >
    学习使用 MCP 检查器
  </Card>
</CardGroup>
